package net.cyndeline.itemEventFactory

import net.cyndeline.entitySystem.EntityRef
import net.cyndeline.entitySystem.Event

/**
 * Fetches the events that should be sent as a result of using
 * a particular item. Retrieving these events does not cause any side-effects
 * to occur until they are actually sent to their recipients.
 */
trait ItemActivation {
  
  /**
   * Retrieves a list of events and their recipients.
   * 
   * @param levels How many levels of the item that should be activated.
   * @param user user The user of the item.
   * @param targets Every entity inside the target area of the item.
   * @return A list of entities mapped to the events that should be sent to
   * 		 them. Based on how the action selects targets, every entity in the
   *    	 target list might not be included.
   */
  def events(levels: Set[Int], user: EntityRef, targets: List[EntityRef]): List[(EntityRef, List[Event])]
}